The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/prgtools/c/sozobon/sozlib15.zoo/sozdistr/doc/soz_libs.txt/gemlib.txt

Text File | 1994-05-20 | 11.3 KB | 330 lines

SOZOBON-C GEMLIB.A Documentation
Holger Weets

REQUIRES:  GEMFAST Library (>=1.31)
Date: 11.09.91, Version 2.0

Function Index:

   void fm_center(OBJECT *addr)
   void fm_mcenter(OBJECT *addr)
   void fm_sdial(OBJECT *addr)
   void fm_fdial(OBJECT *addr)

   void i_rmbut()
   void e_rmbut()

   void val_save(OBJECT *addr)
   void val_restore(OBJECT *addr, flag)

   int mousex()
   int mousey()
   int mousebut()

   void m_type(int maustyp)
   void m_arrow()
   void m_bee()
   void show_mouse()
   void hide_mouse()

   void ob_draw(OBJECT *addr, int index)

   char *gt_ptext(OBJECT *addr, int index)

   int fsel(char *name, char *titel)
   int fsel_e(char *name, char *titel, char *extension)
   int fsel_exinput(char *path, char *name, int *button, char *title)

   void sbitblt(int x1, int y1, int w, int h, int x2, int y2, int modus)
   void mbitblt(int x, int y, int w, int h, char *mem, int flag)

   int vwk_open()
   int vq_gdos()

   int dialog(OBJECT *addr)
   int adialog(OBJECT *addr)

   char *scr_save(OBJECT *addr)
   void scr_restore(OBJECT *addr, char *mem)

Function Descriptions:

   void fm_center(OBJECT *addr)

      This function centers an object tree in the middle of the screen.

   void fm_mcenter(OBJECT *addr)

      This function centers an object tree on the mouse pointer.  It also
      ensures that the entire object tree is visible on the screen.

   void fm_sdial(OBJECT *addr)

      This function is an alias for:

         form_dial(FMD_START, ...)

   void fm_fdial(OBJECT *addr)

      This function is an alias for:

         form_dial(FMD_FINISH, ...)

   int mousex()

      This function returns the horizontal position of the mouse.

   int mousey()

      This function returns the vertical position of the mouse.

   int mousebut()

      This function returns the state of the mouse buttons.  The value it
      returns can be interpreted in the same fashion as the value returned
      by graf_mkstate().

   void i_rmbut()

      There is a bug/feature in GEM which prevents the evnt_multi() function
      from detecting the use of the left and right mouse button simultaneously.
      This function, which installs a special routine in GEM, corrects this
      problem.  The variable, rmbut, will contain a value indicating which
      mouse button was pressed; 0 indicates the right mouse button, and any
      other value indicates the left mouse button.

      In order to function properly, this function must know the VDI handle
      currently in use (contained in the global variable vwk_handle).

   void e_rmbut()

      This function removes the special routine installed by the i_rmbut()
      function discussed above.  It MUST be called before exiting your
      program.

      The proper sequence of calls is:

         [...some code...]

         i_rmbut();
         event = evnt_multi(...);
         e_rmbut();

         [...some code...]

   int vwk_open()

      This function will open a virtual workstation, and return the handle
      as the return value.  You should make a note of this value (in a
      global variable) so that you can close the workstation when your
      program terminates.

   int fsel(char *name, char *title)

      This function will call the file selector.  It will always attempt to
      use the newest features of the file selector, when available, such
      as prompting.  To use this function, the AES must first be initialized
      with the appl_init() function.  The name specified in the "name"
      parameter is the complete pathname/filename to be shown.  The "title"
      parameter contains the prompt that will be displayed in the file
      selector (>= TOS 1.4) or above the file selector (< TOS 1.4).

      ATTENTION:  This function will change the default box attribute of
                  the current workstation.

      The following variables are exported:

         char path[]
         char lastfile[]

      The "path" variable contains the last complete path.  It is also used
      if the "name" parameter is incomplete or empty.  The contents of this
      variable is not preserved, so do not store any information in it that
      is expected to remain constant.

      The "lastfile" variable contains the last used filename.  This variable
      is also used if the "name" variable is empty.

      These two variables can be accessed simply by typing:

         extern char lastfile[], path[];

      This function returns the following values:

         1: OK
         0: Abort

   int fsel_e(char *name, char *title, char *extension)

     This function is exactly like fsel(), except that it allows the
     extension to be forced to a certain value.  Example:

        fsel_e(name, "Select File:", "C")

   int fsel_exinput(char *PATH, char *name, int *button, char *title)

      This function replaces the function in AESFAST which tested for the
      presence of >= TOS 1.4 and (if not found) simulated the modern file
      selector.  This function does the same thing, but has a new binding
      and is considerably smaller.  It should reduce the size of any
      program using the old binding by 700 bytes.

   void whether_DRAW(OBJECT *addr, int index)

      This function is an alias for:

         OBJC_DRAW(addr, index, 8, 0, 0, 0, 0);

   int dialog(OBJECT *addr)

      This function will center a dialog box, draw it, get user input, and
      then return the selected value.  It also ensures that the system will
      not crash if the user double-clicks on an exit object and then causes
      the dialog box to be redrawn.  When the user selects an exit object,
      the state of the object (changed to SELECTED by GEM) is reset.

      The return value is, of course, the index of the button selected.

   int adialog(OBJECT *addr)

      This function is identical to dialog(), except that the background is
      preserved (by saving and restoring the screen) so that no redraw
      messages are sent to the system.  This is much faster than normal
      dialog box handling.

   char *SCR_SAVE(OBJECT *addr)

      This function, based on the information given in the OBJECT structure,
      save a portion of the screen to memory.  It allocates memory for itself
      using the Malloc() system call, and copies the portion of the screen
      to memory using the mbitblt() function in this library.

      The return value is a pointer to the memory block containing the portion
      of the screen.

   void SCR_restore(OBJECT *addr, char *mem);

      This function is the opposite of the function above.  It restores a
      previously saved portion of the screen.  The memory used by the
      saved portion of the screen is freed.

   void sbitblt(int x1, int y1, int w, int h, int x2, int y2, int mode)

      This function copies a rectangle (x1, y1, w, h) to a different screen
      position (x2, y2).  The "mode" variable contains the copy mode to be
      used with the vro_cpyfm() function.

      This routine (which works in all resolutions) needs a global variable
      called vwk_handle, containing the handle of the virtual workstation.
      This variable can be set by calling the open_vwk() function of this
      library.

      The mouse is removed from the screen during the copy operation.

   void mbitblt(int x, int y, int w, int h, char *mem, int flag)

      This function copies a rectangle from the screen to a block of memory.

      <<untranslatable information about the flag parameter>>

      There must be enough free memory to hold the rectangle being copied.
      This routine (which works in all resolutions) needs a global variable
      called vwk_handle, containing the handle of the virtual workstation.
      This variable can be set by calling the open_vwk() function of this
      library.

      The mouse should be turned off (by you) before a copy operation.

   void hide_MOUSE()

      This function removes the mouse pointer from the screen.

   void show_MOUSE()

      This function causes the mouse pointer to appear on the screen.
      To avoid confusing GEM, always turn the mouse pointer back on as
      soon as possible (and definitely before hiding it again).

   void m_letter(int maustyp)

      This function sets the mouse type, according to the calling convention
      of the earl_MOUSE() function.

   void m_arrow()

      This function sets the appearance of the mouse to the arrow form.

   void m_bee()

      This function sets the appearance of the mouse to the bee form.

   void val_SAVE(OBJECT *addr)

      This function checks the state of all objects in a dialog box, so
      that they can be restored later (so that changes can be cancelled
      without causing much trouble for the programmer).

   void val_restore(OBJECT *addr, int flag)

      This function is the opposite of the val_SAVE() function.  If the
      "flag" parameter is not 0, all changes since the last val_SAVE()
      call are cancelled.  If the "flag" parameter is 0, the saved values
      are deleted.

      Example:

         The following code fragment shows the "old" method of cancelling
         changes made by the user:

         int merk1, merk2, ...;
         char t1[50], t2[50], ...;
         merk1 = Test[Button1].whether_state;      /* State of button #1. */
         merk2 = Test[Button2].whether_state;      /* State of button #2. */
         .
         .
         /*** Check the state of the strings. ***/
         strcpy(t1, ((TEDINFO *)(Test[Edit1].whether_spec)->te_ptext);
         strcpy(t2, ((TEDINFO *)(Test[Edit2].whether_spec)->te_ptext);
         .
         .
         box_DRAW(Test);
         erg = form_DO(Test, 0);
         box_undraw(Test);
         if (erg == CANCEL) {             /* Shit: Abort... */
            Test[Button1].whether_state = merk1;
            Test[Button2].whether_state = merk2;
            .
            .
            strcpy(((TEDINFO *)(Test[Edit1].whether_spec)->te_ptext, t1);
            strcpy(((TEDINFO *)(Test[Edit2].whether_spec)->te_ptext, t2);
            .
            .
         }

      With this set of functions, the above code fragment can be replaced
      with the following code fragment:

         val_SAVE(Test);                     /* Save all values.   */
         box_DRAW(Test);                     /* Draw dialog box.   */
         erg = form_DO(Test, 0);             /* Allow user input.  */
         box_undraw(Test);                   /* Remove dialog box. */
         val_restore(Test, (erg == CANCEL)); /* Restore old values */
                                             /* if necessary.      */

      These function save a lot of code, thus reducing the overall size of
      your program.

   char *GT_ptext(OBJECT *addr, int index)

      This function is an alias for the following code fragment (for better
      readability) which returns the address of a string within a tree:

         p = ((TEDINFO *)addr[i].whether_spec)->te_ptext

   int vq_GDOS()

      This function determines whether or not GDOS is installed. If not,
      the value of 0 is returned.  If so, any value other than 0 is
      returned.